## Problem

Orthomosaics consist of several stitched aerial photos taken with the help of a drone. While taking a photo a passing
car that is partially off-screen can occur and only *one part* of it would be visible. But while taking the next
photo, this car would have already passed, and the *second part* will not appear on final orthomosaic. This leads to
generation of defective 3D objects when creating SfM map.

Using **bordercars** you can detect and filter out all cars (not only clipped ones) on the borders of aerial images
individually or of whole orthomosaic in TIFF format. In the second case, the cars will also be found at the joints
of the stitched aerial images.

----

Ортофотопланы состоят из нескольких сшитых аэрофотоснимков, сделанных с помощью дрона. Случается такое, что во время
фотографирования проезжающая машина оказалась частично за кадром и видно лишь *одну её часть*. Но во время следующего
фотографирования машина уже проехала, и *вторая часть* в конечный ортофотоплан не попадает. Это ведет к тому, что при
создании SfM карты появляются дефектные 3D объекты.

С помощью **bordercars** детектировать и фильтровать все машины (не только обрезанные) на краях аэрофотоснимков по
отдельности или в составе ортофотоплана в TIFF формате. Во втором случае машины будут выделяться также на стыках сшитых
аэрофотоснимков.

## Preparation

Clone **bordercars** in your project directory:

    git clone https://gitverse.ru/sc/makarov/bordercars.git

For automatic dependencies installation with CUDA support run:

    pip install bordercars/. && mim install mmcv-full mmdet mmrotate

If you need to install **bordercars** manually (automatic installation fails, or you do not need CUDA), run:

1. Install PyTorch. With CUDA support:

    ```pip install torch torchvision torchaudio```

    CPU only:

    ```pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu```

2. Install dependencies:

    ```pip install -U opencv-python tifffile openmim && mim install mmcv-full mmdet mmrotate```

To install MMRotate compatible models and their configurations run:

    mim download mmrotate --config rotated_fcos_csl_gaussian_r50_fpn_1x_dota_le90 --dest .

Change **rotated_fcos_csl_gaussian_r50_fpn_1x_dota_le90** with the model name of you choice. As a result, a *.pth*
model file and a *.py* python config file will be downloaded to your project directory (change *--dest* from **.** to
another path to switch destination). 

Currently, 2 models have been proven to be accurate at detecting cars on the border, both based on *Rotated FCOS (Fully
Convolutional One-Stage Object Detection)*. **rotated_fcos_csl_gaussian_r50_fpn_1x_dota_le90** is theoretically better
when processing bigger images (tested on 10000x10000), whereas **rotated_fcos_r50_fpn_1x_dota_le90** better processes
smaller images (tested on 2000x2000).


## Usage

Import border cars detector class with ```from bordercars.detector import Detector``` and use its PEP8 documented
methods which include orthomosaic inference (on class object *call*), bounding box manipulations and **draw** method
that allows to draw bounding boxes on top of orthomosaic and save it for debugging purposes. When initializing
*Detector* class object, pass PyTorch model file and its corresponding python config file from preinstalled choices or
of your own.

Import border cars detector test utility with ```from bordercars.test_detector import test``` and use this function for
testing purposes. It processes **test.tif** orthomosaic (either yours or an example from Yandex Disk that will be
downloaded automatically if not found) with chosen model. After that, bounding boxes list as a text file and a copy of
orthomosaic with drawn bounding boxes are saved to *results* folder in your project directory.